Skip to content

Adopt ExDoc & Move Documentation In-Tree #2973

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Open
wants to merge 6 commits into
base: main
Choose a base branch
from
Open

Adopt ExDoc & Move Documentation In-Tree #2973

wants to merge 6 commits into from

Conversation

@jessestimpson
Copy link
Contributor

@jessestimpson jessestimpson commented Sep 28, 2025 •
edited
Loading

This PR uses ExDoc for docs generation and moves all documentation source into the main rebar3 repository.

The primary goal is to bring rebar3's documentation process in line with modern Erlang community standards, enhancing discoverability, familiarity, and contributor experience.

Demo

rebar3exdocdemo.stimpson.io

For demonstration purposes, I've hosted the combined rebar3 ExDocs at the location above. I'll keep them up and running for the lifetime of this PR.

Proposal

This PR proposes three major changes:

  1. Move Documentation Source In-Tree: The source files for documentation (currently in the separate rebar3.org included directly in the rebar3 project.
  2. Adopt ExDoc for Generation
  3. Hosting: Create hexdocs.pm/rebar3

Motivation

1. Familiarity & Community Alignment

  • Standardization: ExDoc is the standard documentation tool across the Erlang/Elixir ecosystem, used by OTP, Elixir, and the majority of popular libraries.
  • Reduced Friction: By following this convention, new and experienced contributors alike can navigate and understand the documentation process much faster.

2. Enhanced Discoverability

  • Expected Locations: A new user would likely look for documentation at erlang.org or HexDocs. Currently, the documentation is not hosted in either.

3. Facilitating Contribution

  • Easy Local Generation: Contributors can now easily generate a complete, local version of the documentation with a simple command, viewing their changes before submitting. (And without npm 😄 )
  • Higher-Quality PRs: A simpler local build process increases contributor comfort and naturally leads to more comprehensive, higher-quality documentation improvements.

4. Clear Public API Definition

  • Convention-Driven Clarity: ExDoc's default conventions inherently clarify the public API. Any module that appears in the "Modules" section is considered public.
  • Robust Plugins: This clear distinction will help developers building rebar3 plugins create more robust and stable integrations by knowing exactly which parts of rebar3's API they can safely rely on.

Progress

  • Copy docs content from https://github.com/tsloughter/rebar3.org.git and rework as needed for ExDoc formatting and linking
  • Add docs profile to rebar.config
  • Generate docs with ./rebar3 as docs ex_doc --app rebar
  • All content changes summarized in commit message
  • Support for groups_for_extras
  • Restrict module inclusion to public API only (i.e. -moduledoc false. where appropriate)

@tsloughter
Copy link
Collaborator

tsloughter commented Sep 29, 2025

Love it!

ferd
ferd reviewed Sep 30, 2025
View reviewed changes
Copy link
Collaborator

@ferd ferd left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I like it as well. I think we'd have to crystallize some of the approach chosen to be broadly compatible with the project (version support, dynamism supported).

Some of the key features of the main site are also the download links on the landing page which no longer exist here, but could certainly be unified a bit better.

I think this is worth pursuing.

@jessestimpson
Copy link
Contributor Author

jessestimpson commented Sep 30, 2025

Thanks for the feedback. I'll update here with the next iteration, hopefully by the weekend.

For the record, I'm hoping we can get rebar_ex_doc plugin support for groups_for_extras to keep the correct docs organization. The current demo ignores the metadata from the _index.md files.

jelly-beam/rebar3_ex_doc#120

@jessestimpson
Add docs from rebar3.org, reworked for ExDoc
f68fcf6 
- Copy rebar3.org content/en/docs to docs
- Remove Hugo headers in all md files
- Where possible, move Hugo descriptions to quote blocks under the h1
- Remove search.md
- Create package_management/publishing-packages.md from _index.md
- Remove content/en/_index.html (the rebar3.org home page)
- Create testing/introduction.md from testing/_index.md
- Remove _index.md from about, configuration, deployment, extending, and tutorials (only contained generic descriptions)
- Tweak markdown tables to render correctly in ExDoc (README, configuration.md, commands.md, building_plugins.md)
- Remove <br> from table cells
- Rework blocks/callout to Admonitions `{: .warning}` and `{: .info}`
- Fix various broken links (e.g. plugins.md publishing, aliases sections, in configuration.md cover section)
- Convert internal doc linking to ExDoc paths
@jessestimpson
Hack in support for groups_for_extras
987d920
@jessestimpson
Copy link
Contributor Author

jessestimpson commented Oct 5, 2025

Updates:

  • Removed doc.config[.script]
  • Doc content now in the source tree
  • Adjusted formatting and linking to fit ExDoc spec. Unfortunately, review of these changes will be challenging since it's a copy from another repo. I suppose I should have committed the base files first to allow diffing between commits, but I didn't think of it until now.
  • Updated demo page with latest
  • Created checklist in main PR description with remaining items

@jessestimpson jessestimpson changed the title Draft: Adopt ExDoc & Move Documentation In-Tree Adopt ExDoc & Move Documentation In-Tree Oct 5, 2025
ferd
ferd reviewed Oct 6, 2025
View reviewed changes
@jessestimpson
Copy link
Contributor Author

jessestimpson commented Nov 17, 2025

rebar3_ex_doc 0.2.31 added support for groups_for_extras, and I put the README urls back to rebar3.org.

Next I will continue with restricting visibility of modules to only those expected as part of the public API.

@jessestimpson jessestimpson marked this pull request as ready for review November 17, 2025 01:12
@jessestimpson
Copy link
Contributor Author

jessestimpson commented Nov 17, 2025

@ferd @tsloughter This PR is ready for review. The latest is hosted at the same demo link.

Known issue: providers, provider, and any other public API module from the vendor dir aren't included in the docs. I wasn't able to find a config option in ExDoc to specify additional source dirs.

There will be some changes to be made after it's merged that have to be orchestrated. Please let me know how I can assist further.

  1. Publishing the generated docs to hexdocs using a maintainer's account
  2. Changes to rebar3.org web server to redirect to hexdocs
  3. Removal of doc content from rebar3.org git repo?
  4. Any GitHub actions that may exist?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@ferd ferd ferd left review comments

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

3 participants

@jessestimpson @tsloughter @ferd